Install

First of all, you have to install R, see this page.
We recommend RStudio as a GUI for R RStudio it is convenient, useful and easy to use.
When you installed Tango, if R was already installed before, the RTango install script has been executed so you don't need anything more to install.
If you installed R after installing Tango, then you'll have to run the script again, for that just run ImageJ or Fiji with Tango, and then in the Tango menu choose "Install RTango". That's it.
If You want to install RTango without Tango, you can, you just have to download the script and run it.

First RTango session

Create a new RTango session

library('rtango') # This will load rtango package into the R session
session = tangoSession$new() 
session$initFields() # This will create a new RTango session

Connect your R session to Tango database

First of all, RTango is a R client for MongoDB Tango database so you need to find the Tango server. Two different cases here :

If you did install Tango and ImageJ on the same computer you're using, you have to use :

session$addConnection() # This will connect your R Session to Tango database

If you installed Tango and ImageJ on another computer on the same network, you have to find its hostname (DNS hostname) or its IP address.
- If your computer is called "tango" on the network, use :

session$addConnection(host='tango') # This will connect your R session to Tango database

If your computer has the IP address 192.168.1.2, use :

session$addConnection(host='192.168.1.2') # This will connect your R session to Tango database

R should display on the screen all the projects it will find in the database.

[1] "tango_Johnny_SeriousStuff"         "tango_jean_GM06_Immuno"            "tango_jean_ImmunoFishGM06990"      "tango_jean_GM12878_FISH3D"        
 [5] "tango_jean_GM06990_ImmunoFISH"     "tango_jean_CycleGM06_2"            "tango_Franz_FL120828-FISH3D"       "tango_jean_GM12878_global_org"    
 [9] "tango_jean_CycleGM06"              "tango_jean_FL121108_GMFISH"        "tango_jean_ImmunoMES"              "tango_jean_MEF_HS"                
[13] "tango_jean_JO121127_MOPFIXGM06990" "tango_Franz_Test1"

exclaim Note that the names all have a suffix, thus have this form tango_username_projectName. This is the complete name of the project that rTango uses.
Following code gives informations about experiments in the "firstProject" :

session$listExperiments(projectName="tango_johnny_firstProject")
[1] "firstExperiment"
# if you use a remote mongoDB server
session$listExperiments(projectName="tango_johnny_firstProject",connectionName="192.168.1.2")
[1] "firstExperiment"

Add an experiment to your session

If you followed the Getting Started guide, you already have one project and one experiment in your database, so let's retrieve data by doing this (don't forget to change project name, username and experiment name if chose different ones):

session$addExperiment(
   projectName='tango_johnny_firstProject',
   experimentName='firstExperiment'
)

Don't forget to mention the host in case you chose another computer for Tango and ImageJ for example:

session$addExperiment(
   host='192.168.1.2',
   projectName='tango_johnny_firstProject',
   experimentName='firstExperiment'
)

Now we shall focus on the experiment. Execute the command below after replacing all the names:

exp = session$workspaces$default$localhost$tango_johnny_firstProject$firstExperiment

$worspaces doesn't have to be changed, ever.
$default is the name of the default workspace of your session.
$localhost is the name of the computer where you put the database, and probably also Tango and ImageJ.
$tango_johnny_firstProject is the name of the project, you may have to change it.
$firstExperiment is the name of your experiment in tango interface.
Once it's done you should see an object of type experiment in RStudio data browser.

Data Extraction

Measurement are stored in the database, and can be retrieved directly from R as dataframe objects.
Each measurement is associated to a name (that can be edited in TANGO) and one or several structures.
Name and associated structures of a measurement can be seen in the interface of TANGO, either in the edit experiment tab or in the data browsing tab. See the tutorial for more informations.
There are two main commands to extract data from the database, they can extract several measurements of the same kind at once.

Extract Object Data

These data corresponds to measurement performed on a single object of a segmented structure (1 value per object), such as the volume of an object. Thus they can be indexed by the index of the object when the parameter addIdx=TRUE

dataframe1=exp$extractObjectData(0,keys=c('volume_unit','compacity'),addIdx=TRUE)

This code will extract the volume_unit and the compacity of all objects found in the structure of index 0(it is always the nucleus in Tango), and build the following dataframe :

Extract Structure Data

These data corresponds to measurement performed between several structures.
A specific case is measurement between two objects of two structures (such as distance). In this case only, dataframe can be indexed by the index of the each of objects (2 indexes) when the parameter addIdx is set to true; Make sure you extract only this kind of measurements at once when addIdx is set to TRUE.
The other kind of measurement can be arrays of undefined length, so one have to make sure they all have the same length, or extract only one per dataframe.

dataframe2=exp$extractStructureData(c('CenpA','C23'),keys=c('distBB','distCC'),addIdx=TRUE)

This code will retrieve distBB (border to border distance) and distCC (center to center distance) measurements between objects of structure CenpA and objects of structure C23.

On this snapshot, we can see that :

The distance between the 1st object border in CenpA structure and the 2nd object border in C23 structure is 4.33274838
The distance between the 3rd object center in CenpA structure and the 2nd object center in C23 structure is 3.7281815

Play with Selections

When analysing data with R, it can be useful to visualize (or process) the underlying images.
To make a link between data in R and images, we introduced Selections, that can be generated from R and used in TANGO, or edited in TANGO and used in R.
Selection can represent a subset of the nuclei of an experiment, or the objects contained in nuclei.

Selections from R to TANGO

Let's start by creating a subset of our objects:
Try this command :

dataframe3=subset(dataframe2,subset=distBB<0.1) # defines a sub-population of objects by a criterion
selection1=exp$extractSelection(dataframe3) # creates a selection
selection1$save() #records it so that it can be seen in tango.

Now look at dataframe3. The R subset function has filtered rows so only those where distBB is less than 0.1 will remain.

By default, the save command will generate a selection named "currentSelection" in TANGO and override it if existing.
A name can be specified, and if override is set to false, it will create a unique name.

Now look at the results in Tango, in the data tab, by clicking on the >Selections> button.

Only nuclei contained in the selected Fields are displayed in the list.

Selections from TANGO to R

A selection created or edited in TANGO can be retrieved in R:

selections = exp$selections #returns a list of all the selections, indexes by their name
curSel = selections[["currentSelection"]] #takes only one selection
nuc.list = curSel$getFilter() #extracts the list of selected nuclei
# this list can be used to created a subset of a data.frame for instance (providing the data.frame "df" has a column names "nucleus.id"):
df.subset = df[df$nucleus.id%in%nuc.list, ]

Interactive plots

Install Acinonyx

Refer to this page.
See also the Acinonyx documentation here.

Generate an interactive plot

In this simple example, we will generate an histogram of eroded volume fraction of centromeres, as generated in the tutorial

#Extracting data from database:
df1 = exp$extractObjectData(1, keys=c("volume_unit", "CenpA_average", "CenpA_integratedDensity", "evf"), addIdx=TRUE)

#generate interactive histogram of evf
library("Acinonyx")
ihist(df1$evf)

exclaim Acinonyx uses a java virtual machine, so when displaying many plots you might get the error: java.lang.OutOfMemoryError: Java heap space
In this case:
The -Xmx flag to increase the heap size (and -Xms to increase the stack size)
The solution is to supply this -Xmx parameter before the Java Virtual Machine is initialized. From the R shell, invoke this:

options( java.parameters = "-Xmx4g" )

Select a subset of the population and record the selection

# get the index of the interactively selected objects. Each one corresponds to a line in the dataframe df1 and to a single centromere
sel = iset.selected() 
# convert to a tango selection: 
df1.subset=df1[sel,] # generated a dataframe with only the selected lines
sel1 = exp$extractSelection(df1.subset) # converts the dataframe into a selection
sel1$save() #saves the selection under the name "currentSelection" and override it if existing.

A selection names "currentSelection" will appear in the selection list, containing only the selected centromeres.

Image Cytometry

R contains flow-cytometry packages, that provides many functions for processing and visualizing flow-cytometry data.
Many of those functionalities are relevant for image-cytometry analysis. Thus we developed a small package in order to ensure compatibility with those tools.
In this section we provide an example using iFLow, a GUI based visualization for flow cytometry.

Install iFlow :

source("http://bioconductor.org/biocLite.R")
> biocLite("iFlow")

Install rtango.flow package

download rtango.flow package and save it.
install the package in R

> install.packages('/path/to/your/download/rtango.flow_1.0.tar.gz', repos = NULL)

Don't forget to replace /path/to/your/download with the real path to the file you just download.

Import data to iFlow

flowCore and iFLow use a different format of data, thus dataframes generated by rtango have to be converted:

library(rtango.flow)
workFlow = tangoWorkFlow$new(dataframes=list(A=dataframe1,B=dataframe2,C=dataframe3))
iFlow()

When the iFlow interface shows up, choose the File Menu and "Load" and select "tangoFlowSet".
Please read the docs for making filters on the data coming from tango.

Export selection to TANGO

iFlow allows one to create gates in order to select a sub-population of the data.
Our package allows one to retrieve the sub-populations and visualize the corresponding images in TANGO.

session$extractSelectionsFromWorkFlow(workFlow)

Now look back in tango interface, you should see selections there.

Getting started with RTango